<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Creates an index on the given field(s), or does nothing if the index 
   already exists</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.drop.html">MongoCollection::drop</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocollection.ensureindex" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">MongoCollection::ensureIndex</h1>
  <p class="verinfo">(PECL mongo &gt;=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::ensureIndex</span> &mdash; <span class="dc-title">
   Creates an index on the given field(s), or does nothing if the index 
   already exists
  </span></p>

 </div>

 <div class="refsect1 description" id="refsect1-mongocollection.ensureindex-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>MongoCollection::ensureIndex</strong></span>
    ( <span class="methodparam"><span class="type"><span class="type string|array">string|array</span></span> <code class="parameter">$key|keys</code></span>
   [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array()</span></span>
  ] )</div>

  <p class="para rdfs-comment">
   This method creates an index on the collection and the specified fields.
   The key specification can either be just a single field name as string, or an
   array containing one or more field names with their sort direction.
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-mongocollection.ensureindex-parameters"> 
  <h3 class="title">参数</h3> 
  <p class="para">
   <dl>

    
     <dt>

      <em><code class="parameter">keys</code></em>
     </dt>

     <dd>

      <p class="para">
       An array of fields by which to sort the index on. Each element in the
       array has as key the field name, and as value either
       <em>1</em> for ascending sort, or <em>-1</em> for
       descending sort.
      </p>
     </dd>

       
    
     <dt>

      <em><code class="parameter">options</code></em>
     </dt>

     <dd>

      <p class="para">
       This parameter is an associative array of the form 
       <em>array(&quot;optionname&quot; =&gt; &lt;boolean&gt;, ...)</em>. Currently 
       supported options are: 
       <ul class="itemizedlist">
        <li class="listitem"><p class="para"><em>&quot;w&quot;</em></p><p class="para">See <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a>. The default value for <a href="class.mongoclient.html" class="classname">MongoClient</a> is <em>1</em>.</p></li>
        <li class="listitem">
         <p class="para">
          <em>&quot;unique&quot;</em>
         </p>
         <p class="para">
          Create a unique index.
         </p>
         <div class="warning"><strong class="warning">Warning</strong>
          <p class="para">
           A unique index cannot be created on a field if multiple existing
           documents do not contain the field. The field is effectively <strong><code>NULL</code></strong>
           for these documents and thus already non-unique. Sparse indexing may
           be used to overcome this, since it will prevent documents without the
           field from being indexed.
          </p>
         </div>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;dropDups&quot;</em>
         </p>
         <p class="para">
          If a unique index is being created and duplicate values exist, drop
          all but one duplicate value.
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;sparse&quot;</em>
         </p>
         <p class="para">
          Create a sparse index, which only includes documents containing the
          field. This option is only compatible with single-field indexes.
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;expireAfterSeconds&quot;</em>
         </p>
         <p class="para">
          The value of this option should specify the number of seconds after
          which a document should be considered expired and automatically
          removed from the collection. This option is only compatible with
          single-field indexes where the field will contain
          <a href="class.mongodate.html" class="classname">MongoDate</a> values.
         </p>
         <p class="para">
          This feature is available in MongoDB 2.2+. See
          <a href="http://docs.mongodb.org/manual/tutorial/expire-data/" class="link external">&raquo;&nbsp;Expire Data from Collections by Setting TTL</a>
          for more information.
         </p>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;background&quot;</em>
         </p>
         <p class="para">
          By default, index creation is a blocking operation and will stop other
          operations on the database from proceeding until completed. If you
          specify <strong><code>TRUE</code></strong> for this option, the index will be created in the
          background while other operations are taking place.
         </p>
         <div class="warning"><strong class="warning">Warning</strong>
          <p class="para">
           Prior to MongoDB 2.1.0, the index build operation is not a background
           build when it replicates to secondaries, irrespective of this option.
           See
           <a href="http://docs.mongodb.org/manual/tutorial/build-indexes-on-replica-sets/" class="link external">&raquo;&nbsp;Building Indexes with Replica Sets</a>
           for more information.
          </p>
         </div>
        </li>
        <li class="listitem">
         <p class="para">
          <em>&quot;name&quot;</em>
         </p>
         <p class="para">
          This option allows you to override the algorithm that the driver
          uses to create an index name and specify your own. This can be
          useful if you are indexing many keys and Mongo complains about the
          index name being too long.
         </p>
        </li>
        <li class="listitem"><p class="para"><em>&quot;timeout&quot;</em></p><p class="para">Integer, defaults to <em>MongoCursor::$timeout</em>.  If &quot;safe&quot; is set, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> will be thrown.</p></li>
        <li class="listitem"><p class="para"><em>&quot;safe&quot;</em></p><p class="para"><em class="emphasis">Deprecated</em>. Please use the <a href="mongo.writeconcerns.html" class="link">WriteConcern</a> <em>w</em> option.</p></li>
       </ul>
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-mongocollection.ensureindex-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   Returns an array containing the status of the index creation if the
   <em>&quot;w&quot;</em> option is set. Otherwise, returns <strong><code>TRUE</code></strong>.
  </p>
  <p class="para">
   Fields in the status array are described in the documentation for
   <span class="function"><a href="mongocollection.insert.html" class="function">MongoCollection::insert()</a></span>.
  </p>
 </div>


 <div class="refsect1 changelog" id="refsect1-mongocollection.ensureindex-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>1.3.0</td>
       <td>
        The <em><code class="parameter">options</code></em> parameter no longer accepts a boolean
        to signify a unique index. Instead, this now has to be done with
        <em>array(&#039;unique&#039; =&gt; true)</em>.
       </td>
      </tr>

      <tr>
       <td>1.2.11</td>
       <td>
        Emits <strong><code>E_DEPRECATED</code></strong> when
        <em><code class="parameter">options</code></em> is <span class="type"><span class="type scalar">scalar</span></span>.
       </td>
      </tr>

      <tr>
       <td>1.2.0</td>
       <td>Added <em>&quot;timeout&quot;</em> option.</td>
      </tr>

      <tr>
       <td>1.0.11</td>
       <td>
        <p class="para">
         The <em>&quot;safe&quot;</em> option will trigger a primary failover,
         if necessary.
        </p>
        <p class="para">
         <a href="class.mongoexception.html" class="classname">MongoException</a> will be thrown if the index name
         (either generated or set) is longer than 128 bytes.
        </p>
       </td>
      </tr>

      <tr>
       <td>1.0.5</td>
       <td>
        Added the <em>&quot;name&quot;</em> option to override index name
        creation.
       </td>
      </tr>

      <tr>
       <td>1.0.2</td>
       <td>
        Changed <em><code class="parameter">options</code></em> parameter from boolean to array.
        Pre-1.0.2, the second parameter was an optional boolean value specifying
        a unique index.
       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-mongocollection.ensureindex-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   Throws <a href="class.mongoexception.html" class="classname">MongoException</a> if the index name is longer than
   128 bytes. (Version 1.0.11+)
  </p>
  <p class="para">Throws <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> if the &quot;w&quot; option is set and the write fails.</p><p class="para">Throws <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> if the &quot;w&quot; option is set to a value greater than one and the operation takes longer than <var class="varname"><var class="varname">MongoCursor::$timeout</var></var> milliseconds to complete.  This does not kill the operation on the server, it is a client-side timeout. The operation in <em>MongoCollection::$wtimeout</em> is milliseconds.</p>
 </div>


 <div class="refsect1 examples" id="refsect1-mongocollection.ensureindex-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1413">
   <p><strong>Example #1 <span class="function"><strong>MongoCollection::ensureIndex()</strong></span> example</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$c&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'foo'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;create&nbsp;an&nbsp;index&nbsp;on&nbsp;'x'&nbsp;ascending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(</span><span style="color: #DD0000">'x'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;create&nbsp;an&nbsp;index&nbsp;on&nbsp;'y'&nbsp;ascending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'y'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">//&nbsp;create&nbsp;an&nbsp;index&nbsp;on&nbsp;'z'&nbsp;ascending&nbsp;and&nbsp;'zz'&nbsp;descending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'z'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'zz'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;-</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">//&nbsp;create&nbsp;a&nbsp;unique&nbsp;index&nbsp;on&nbsp;'x'<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">),&nbsp;array(</span><span style="color: #DD0000">"unique"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">true</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
  <div class="example" id="example-1414">
   <p><strong>Example #2 Drop duplicates example</strong></p>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*<br />&nbsp;*&nbsp;index&nbsp;creation&nbsp;fails,&nbsp;you&nbsp;can't&nbsp;create&nbsp;a&nbsp;unique&nbsp;index&nbsp;on&nbsp;a&nbsp;key&nbsp;with&nbsp;<br />&nbsp;*&nbsp;non-unique&nbsp;values<br />&nbsp;*/<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">),&nbsp;array(</span><span style="color: #DD0000">"unique"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*<br />&nbsp;*&nbsp;index&nbsp;creation&nbsp;succeeds:&nbsp;one&nbsp;of&nbsp;the&nbsp;documents&nbsp;is&nbsp;removed&nbsp;from&nbsp;the&nbsp;collection<br />&nbsp;*/<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">),&nbsp;array(</span><span style="color: #DD0000">"unique"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"dropDups"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*&nbsp;<br />&nbsp;*&nbsp;now&nbsp;we&nbsp;have&nbsp;a&nbsp;unique&nbsp;index,&nbsp;more&nbsp;inserts&nbsp;with&nbsp;the&nbsp;same&nbsp;username&nbsp;(such&nbsp;as&nbsp;the<br />&nbsp;*&nbsp;one&nbsp;below)&nbsp;will&nbsp;fail<br />&nbsp;*/<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>

  <div class="example" id="example-1415">
   <p><strong>Example #3 Geospatial Indexing</strong></p>
   <div class="example-contents"><p>
    Mongo supports geospatial indexes, which allow you to search for documents
    near a given location or within a shape.  For example, to create a 
    geospatial index on the &quot;loc&quot; field:
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"loc"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"2d"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
 </div>


 <div class="refsect1 seealso" id="refsect1-mongocollection.ensureindex-seealso">
  <h3 class="title">参见</h3>
  <p class="para">
   MongoDB core docs on 
   <a href="http://docs.mongodb.org/manual/indexes/" class="link external">&raquo;&nbsp;vanilla indexes</a> and 
   <a href="http://docs.mongodb.org/manual/applications/geospatial-indexes/" class="link external">&raquo;&nbsp;geospatial indexes</a>.
  </p>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.drop.html">MongoCollection::drop</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
